.TH LIBPFM 3  "November, 2002" "" "Linux Programmer's Manual"
.SH NAME
pfm_get_event_name, pfm_get_event_code, pfm_get_event_counters, pfm_get_first_event, pfm_get_next_event \- get event information
.SH SYNOPSIS
.nf
.B #include <perfmon/pfmlib.h>
.sp
.BI "int pfm_get_event_name(int " e ", char **"name);
.BI "int pfm_get_event_code(int " e ", int *"code);
.BI "int pfm_get_event_counters(int " e ", unsigned long "counters "[4]);"
.BI "int pfm_get_first_event(void);"
.BI "int pfm_get_next_event(int "e);
.BI "int pfm_get_event_description(unsigned int " ev ", char **" str);
.sp
.SH DESCRIPTION
The PMU counters can be programmed to measure the number of occurrences
of certain events. The number of events varies from one implementation
to the other. Each event has a name and a code which is used to program
the actual PMU register. Not all event can necessarily be programmed on
any of the available counters due to hardware constraints.
.sp
The library does not directly expose the event code to user applications
because it is not necessary. Instead applications used names to
query the library for particular information about events. Given
a name, the library returns an opaque descriptor to the applications. 
Each descriptor is unique and has no relationship to the event code.
All functions requires the library to be properly initialized.
.sp
The \fBpfm_get_event_name\fR function returns in \fBname\fR the event 
name given its opaque descriptor \fBe\fR. The string representing the 
name must be considered as read only.
.sp
The \fBpfm_get_event_code\fR function returns the event code in \fBcode\fR
given its opaque descriptor \fBe\fR.
.sp
Given an opaque event descriptor \fBe\fR, the \fBpfm_get_event_counters\fR 
function returns a bitmask in the \fBcounters\fR array where each bit set 
represents a PMU counter which can be used to program this event. A PMU 
counter is defined as a matching pair of PMC and PMD, such as PMC4/PMD4.
.sp
It is possible to list all existing events for the detected host PMU
using access functions as the full table of events is not accessible
to the applications. The \fBpfm_get_first_event\fR returns the opaque descriptor
for the first event, then \fBpfm_get_next_event\fR is used to go to the next
event given a descriptor \fBe\fR. After the last event, this function will 
return -1. The typical scan loop is constructed as 
follows:
.sp
.nf
char **name;
int i;
i = pfm_get_first_event();
for(;i != -1; i = pfm_get_next_event(i))
{
   pfm_get_event_name(i, &name);
   printf("%s\\n", name);
}
.fi

The \fBpfm_get_event_description\fR functions returns in \fBstr\fR the
description string associated with the event specified in \fBev\Fr. 
Depending on the PMU model, some events may not have a description in
which case the \fBstr\fR pointer is set to NULL.  Otherwise, a buffer
is allocated to hold the entire description text. It is the responsibility
of the caller to free the buffer when it becomes useless by calling the
\fBfree(3)\fR function.


.SH RETURN
The \fBpfm_get_first_event\fR returns the opaque descriptor of the
first event. The \fBpfm_get_next_event\fR function return the
descriptor for the next event. A value of -1 is returned 
if the last event is passed as argument or if an invalid
event descriptor is given.

All other functions return whether or not the call was successful.
A return value of \fBPFMLIB_SUCCESS\fR indicates success, 
otherwise the value is the error code.
.SH ERRORS
.B PFMLIB_ERR_NOINIT
the library has not been initialized properly.
.TP
.B PFMLIB_ERR_INVAL
the event descriptor is invalid, or the pointer argument is NULL.
.SH AUTHOR
Stephane Eranian <eranian@hpl.hp.com>
.PP
